Software Vault: The Gold Collection

home *** CD-ROM | disk | FTP | other *** search

/ Software Vault: The Gold Collection / Software Vault - The Gold Collection (American Databankers) (1993).ISO / cdr10 / autrd201.zip / MANUAL.DOC < prev next >

Wrap

Text File | 1993-06-16 | 88KB | 1,991 lines

╔═════════════════════════════════════════════════════════════════════╗ ║ ┌──────────┐ ║ ║ │ AUTOREAD │ ║ ║ └──────────┘ ║ ║ ║ ║ A program to allow easy reading of large text files ║ ║ on a computer ║ ║ ║ ║ MANUAL ║ ║ ║ ║ ║ ║ Author: David R Grigg ║ ║ A Product of Rightword Enterprises. ║ ║ (C) Copyright David R Grigg 1991 ║ ║ ║ ║ ║ ║ Version 2.00 ║ ║ December 1992. ║ ║ ║ ║ ┌─────────────────────────────┐ ║ ║ │ CONTACT DETAILS: │ ║ ║ │ David R. Grigg, │ ║ ║ │ 1556 Main Road, │ ║ ║ │ Research, │ ║ ║ │ Victoria 3095, │ ║ ║ │ AUSTRALIA. │ ║ ║ │ │ ║ ║ │ Compuserve: [76264,2530] │ ║ ║ └─────────────────────────────┘ ║ ║ ║ ╚═════════════════════════════════════════════════════════════════════╝ Autoread Manual -i- DISCLAIMER ────────── While every effort has been made to free AUTOREAD from errors, and I can't imagine how AUTOREAD could cause you any problems, as a matter of prudent legality, please heed the following notice: I, David R Grigg, accept NO RESPONSIBILITY OR LIABILITY for any damage that may be caused to your computer, disks or data by the use of AUTOREAD. If this makes you nervous, try AUTOREAD out on a floppy disk first. As a matter of good practice you should always keep regular backups of important files. Autoread Manual -ii- CONTENTS ──────── │ DISCLAIMER .................................................... i │ 1: Introduction .............................................. 1 │ 2: Shareware Notice .......................................... 3 │ 3: Installing AUTOREAD ....................................... 4 │ 4: Files Created by AUTOREAD ................................. 5 │ 5: The AUTOREAD screen ....................................... 6 │ 5.1 Menus and Selecting Choices ............................ 6 │ 5.2 The File Open Dialog Box ............................... 6 │ 5.3 The Document Window .................................... 7 │ 5.4 Window Highlighting .................................... 7 │ 6. A Brief Tour of the AUTOREAD Menu Bar ...................... 9 │ 6.1 The = Menu ............................................. 9 │ 6.2 The File Menu .......................................... 9 │ 6.3 The Document Menu ...................................... 9 │ 6.3 The Chapter Menu ....................................... 9 │ 6.4 The Keywords Menu ..................................... 10 │ 6.5 The Bookmarks Menu .................................... 10 │ 6.6 The Search Menu ....................................... 10 │ 6.7 The Utilities Menu .................................... 11 │ 7: Document Menu ............................................ 12 │ 7.1 View (Home) ........................................... 12 │ 7.2 Top(^Home) ............................................ 12 │ 7.3 Middle ................................................ 12 │ 7.4 Bottom (^End) ......................................... 12 │ 7.5 Line Number ........................................... 13 │ 7.6 Page Number ........................................... 13 │ 7.7 Odd Page Set .......................................... 13 │ 7.8 Even Page Set ......................................... 14 │ 7.9 Preferences ........................................... 14 │ 7.9.1 Chapter Sort Order ............................... 14 │ 7.9.2 Show Level Prefixes and Level Prefix Symbol ...... 15 │ 7.9.3 Offset Display ................................... 15 │ 7.9.4 Save Last Session ................................ 15 │ 7.9.5 Start at Last Session ............................ 15 │ 7.9.6. Save Bookmarks .................................. 15 │ 8: Chapters Menu ............................................ 16 │ 8.1 View (F2) ............................................. 16 │ 8.2 Find(Enter) ........................................... 16 │ 8.3 Add Current Line (Ins or Alt-A) ....................... 17 │ 8.4 Delete ................................................ 17 │ 8.5 Edit .................................................. 17 │ 8.6 Promote and Demote .................................... 17 │ 8.7 Clear ................................................. 17 │ 8.8 Make .................................................. 17 │ 8.9 Textual Make .......................................... 18 │ 8.9.1 A Textual Make Example ........................... 18 │ 8.10 Procedural Make ....................................... 19 │ 8.11 UpperCase Make ....................................... 20 │ 8.12 Problems with Make ................................... 20 │ 8.13 The Stand-Alone Make Utility ......................... 21 │ 8.13.1 C - Clear Chapters .............................. 21 │ 8.13.2 T - Textual Make ................................ 22 │ 8.13.3 N - Numeric Procedural Make ..................... 22 │ 8.13.4 A - Alphabetical Procedural Make ................ 22 │ 8.13.5 U - UpperCase Make .............................. 22 Autoread Manual -iii- │ 8.13.6 Example Make File: .............................. 22 │ 8.13.8 An Important Note! .............................. 22 │ 9: Keywords Menu ............................................ 23 │ 9.1 View (F3) ............................................. 23 │ 9.2 Find (Enter) .......................................... 23 │ 9.3 Add (Ins) ............................................. 23 │ 9.4 Delete (Del) .......................................... 23 │ 9.5 Edit (Ctrl-F3) ........................................ 23 │ 10: Bookmarks Menu .......................................... 24 │ 10.1 View (F4) ............................................ 24 │ 10.2 Find (Enter) ......................................... 24 │ 10.3 Add (Ins) ............................................ 24 │ 10.4 Delete (Del) .......................................... 24 │ 10.5 Edit (Ctrl-F4) ........................................ 25 │ 10.6 Function Key Setting & Finding Marks ................. 25 │ 11: Find Menu ............................................... 26 │ 11.1 Find Text (F5) ....................................... 26 │ 11.2 Last Find (F6) ....................................... 26 │ 11.3 Find In Chapter (Ctrl-F5) ............................ 26 │ 11.4 Last Chapter Find (Ctrl-F6) .......................... 27 │ 12: Utilities Menu .......................................... 28 │ 12.1 Screen Mode .......................................... 28 │ 12.2 Directories .......................................... 28 │ 12.3 Output Text .......................................... 28 │ 12.3.1 Screen .......................................... 29 │ 12.3.2 Chapter ......................................... 29 │ 12.3.3 Lines ........................................... 29 │ 12.3.4 Page Break ...................................... 29 │ 13: The Read-Only Version ................................... 30 │ 14: Acknowledgements ........................................ 31 │ 15: Version History ......................................... 32 │ 15.1 Updates ............................................. 32 │ APPENDIX A: FUNCTION KEY SUMMARY ............................. 34 │ APPENDIX B: COMMAND-LINE OPTIONS ............................. 35 │ APPENDIX C: THE .ARD FILE FORMAT ............................. 36 │ APPENDIX D: LIMITATIONS OF AUTOREAD .......................... 38 │ APPENDIX E: MUSINGS ON THE WRITING OF MANUALS ................ 39 │ APPENDIX F: RAVE REVIEWS AND UNSOLICITED TESTIMONIALS! ....... 40 Autoread Manual -1- 1: Introduction ════════════════ I wrote this program because I often find myself in the situation of having a large text file on my computer's hard disk which I am using because it has some kind of information of value to me. Usually it is the manual for a shareware program. I adore shareware. I think the concept of trusting people to pay a modest fee for software they genuinely find useful is terrific. And I use a lot of shareware (and pay the appropriate registration fees). But the manuals for most shareware programs are distributed as a text file unless you pay extra (and I generally don't). So I end up with very useful manuals in a very NON-useful form: a large text file on my hard disk. Sure, I can print out the manual, but this can consume enormous amounts of time, paper and printer ribbons (the QEDIT manual, for example, is some 5500 lines long). And besides, I can never find the manual when I want it. And even if I can, finding the information I want can be very hard. Aren't computers supposed to make life easier? Yet reading a document on a computer screen is still extremely primitive. Certainly you can use a useful utility like LIST, but this is still missing something. It's hard to navigate around in a large text file, to find the next chapter, or to locate key words. Using the FIND utility in such programs is some help, of course, but you have to type in the key word, and hope you have spelt and punctuated it properly. AUTOREAD is my attempt to fill this perceived gap. It works very much like LIST, but it allows you to progressively establish landmarks in the text and to go instantly to them. AUTOREAD allows the creation of several kinds of 'landmarks': * Chapter Stops * Predefined Keywords * Temporary Bookmarks These are all available via separate windows for easiest possible use. What all this means is that you can very easily create a comprehensive index to a particular text file, enabling you to instantly find the section or information you are looking for. It makes reading a text file on your computer as easy as reading a hard copy, and in some respects easier. Another extremely valuable use of AUTOREAD is for the creation of on- line help facilities. Several companies have purchased site-license agreements for AUTOREAD for just this purpose. The command-line Find Text function means that you can start up AUTOREAD and instantly zip to the particular topic you are interested in. A read-only version of AUTOREAD, called READAUTO, is available so you can create such a help Autoread Manual -2- system but prevent your users from messing up your set-up. Note that one of the very best features of this latest release of AUTOREAD (in my view) is its ability to handle VERY large documents, possibly up to 80MB in size, though indexing such a document might take a while... Autoread Manual -3- 2: Shareware Notice ════════════════════ AUTOREAD took a lot of effort to create. And I am still working on improving it. Please note that AUTOREAD is not, never has been, and never will be free or public domain software. It is shareware. The shareware concept is extremely simple. If you obtain a copy of a shareware program, find it useful to you, and wish to continue using it, you must send the requested shareware fee to the program author. Shareware relies entirely on trust. But it is a concept which has allowed the creation and distribution of a large body of excellent software at very low cost. If you find AUTOREAD of use, please print out and fill in the enclosed LICENSE.DOC document, and send it with the requested $30 shareware fee to: David R Grigg, 1556 Main Road, Research, Victoria 3095 Australia. In return, you will receive the current version of AUTOREAD, registered and free of the annoying opening shareware message, and also free from several limitations on size of document, number of chapters and keywords which are built into the shareware version (I've got to make a living somehow!). For those in the US: personal cheques are acceptable. NOTE: Most commercial software forbids you to make copies of it. But because AUTOREAD is shareware software, you are positively ENCOURAGED to share copies of AUTOREAD around, copy it for your friends, upload it to bulletin boards, etc. The only stipulations are that all those who use AUTOREAD for longer than a trial period of 14 days must pay the required shareware fee, and that AUTOREAD must be distributed with all the associated files, being: AUTOREAD.EXE MANUAL.DOC MANUAL.ARI MANUAL.ARD LICENSE.DOC README.BAT CHAPMAKE.EXE Autoread Manual -4- 3: Installing AUTOREAD ═══════════════════════ AUTOREAD is extremely easy to install. The only file absolutely necessary to operating AUTOREAD is AUTOREAD.EXE, which you should place either into the same directory as the documents you wish to use it on, or (especially if you have a hard disk) into a directory which is listed in your DOS PATH command (this is usually specified in your AUTOEXEC.BAT file). Many hard disk users have a directory called \TOOLS on their hard disk. This is a good place for AUTOREAD. NOTE: if you are upgrading from version 1.10 or before, you may care to install version 2.00 in a different directory from your current version, until you have tried it out. There are a lot of changes in this version, and some features omitted. On balance, I believe this version is much better than the earlier versions, but it would be as well for you to keep your old version of AUTOREAD until you have made sure you are happy with the new version. To use AUTOREAD on a particular text file (as an example, say a file called MANUAL.DOC), you would enter the following at the DOS prompt: AUTOREAD MANUAL.DOC If you don't enter the file name, AUTOREAD will open up, and you can use the File Open menu choice to select the file you want. Alternatively, if you start up with a command line like this:. AUTOREAD *.TXT ...AUTOREAD will start up by showing you the File Open dialog box, showing all the files that fit the specification you gave on the command line. NOTE: If you don't enter a file extension (e.g. the .DOC above), then AUTOREAD will attempt to find a file with the name you have given it, with either of the following extensions: .DOC .TXT If it still can't find the file, it will give up with an error message. Autoread Manual -5- 4: Files Created by AUTOREAD ═════════════════════════════ AUTOREAD maintains at least two different files of its own for every text file that you use it on, and in some circumstances three. If you used it on a document called MANUAL.DOC, for example, AUTOREAD would create the following files: MANUAL.ARI MANUAL.ARD ...and if you chose Save Last Session or Save Bookmarks in the Preferences dialog box (see page 14), the following file: MANUAL.ARB Unless you have changed the text-file since you last read it, the .ARI file will be created only the first time you use AUTOREAD on the text file. The .ARD file, however, may be rewritten many times as you add data or alter preferences. The .ARI file is an index of the starting points of each line of the text file, and enables AUTOREAD to very speedily locate parts of the file. If it offends you to have a lot of additional files in a directory, you can delete this file, but then AUTOREAD will need to recreate it each time you access the text file that it indexes. The .ARD file contains such data as your preferences for this document, a list of chapter stops and their starting lines, a list of keywords, and some other information. Note that the .ARD file is an ordinary text file, which means that you can use a text editor to manipulate it directly. (See APPENDIX C on page 35 for details). Users of versions prior to version 2.00 may wish to note that there have been some minor changes to the format of the .ARD file, most importantly in the order in which information is stored in the file, and in the addition of some new data sections. The .ARB file, saved only if certain preferences are set for the document, contains any bookmarks you have created, and/or the Last Session line number; that is, the line of the document you were viewing when you closed the document (which is stored as bookmark #0). From version 2.00, you can dictate where (ie, in what file directory) these various files are created. This means you can now use AUTOREAD on a file which is located on a write-protected disk, even for example on a CD-ROM, by having the writable files elsewhere. However, unless you specifically tell AUTOREAD otherwise, it will look for these files in the same directory as the source document. Autoread Manual -6- 5: The AUTOREAD screen ═══════════════════════ 5.1: Menus and Selecting Choices ────────────────────────────────────────────────────────────────────── You may well be familiar with using programs with pull-down menus and moveable windows, either under Microsoft Windows, or programs running under DOS which use the same kind of interface, in which case you can probably skip this section of the manual. If you are not using AUTOREAD to read this manual, please start it up now by typing: AUTOREAD MANUAL at the command-line. Note the Menu Bar at the top line of the screen, and the Status Line at the bottom. At any time, you can pull down a menu from any of the choices on the Menu Bar, in any one of several ways: * By clicking on the menu choice with the mouse, if you are using one; * By holding down the Alt key and then pressing the first letter of your desired choice; * By pressing F10 to highlight the first choice on the menu bar, and then using the arrow keys to move across choices, and Enter to select one. Once you have a menu open, you can select a choice either by: * Clicking on the choice with the mouse; * Using the arrow keys to select the item you want and then pressing Enter; * Pressing the key corresponding to the letter in the item which is highlighted in red. * Pressing the key shown to the right of the choice - this is usually called the "hot key" for the action, and not all choices have them. You can also often use the hot key when the menu is not opened up. You will note that many choices are "greyed out" until you open a document. These represent choices which are invalid for the current state of the program. Obviously, you cannot close a document until you have opened one! Note also that the current version of AUTOREAD only allows one document to be open at a time, and so once you have opened a document, the Open choice on the file menu is greyed out. 5.2: The File Open Dialog Box ────────────────────────────────────────────────────────────────────── When you chose Open from the File menu, a dialog box will appear. (A dialog box is just an area on the screen that lets you make choices). Press the TAB key a few times. You will notice that different parts of the box get highlighted. While a section is highlighted, you can either enter text, or make some kind of selection. Of course, using a mouse, all you need to is click on the area which wish to use. Note in particular the green, drop-shadowed "buttons". You can either click on these, or TAB the highlight to them and then press Enter. Autoread Manual -7- With the Open File dialog, you can either enter the file name you want directly in the text input field, or select the wanted file in the scrolling file list. Then just press Enter, or click on the "Open" button to open the nominated file. 5.3: The Document Window ───────────────────────────────────────────────────────────────────── Once you have opened a file, you may see a message on the Status Line showing that AUTOREAD is busy creating an index. When this process is finished, you may see a couple of boxes appear very briefly before disappearing and being replaced by the Document Window. Don't worry about these boxes, which may vanish so fast they appear just to be flashes on your screen - AUTOREAD is just creating windows for chapters, keywords and bookmarks, and then hiding them to get them out of your way. There are several points to note about the Document Window. Firstly, the close button at the top left of the window, a dot of colour with square brackets around it. Clicking on this point will close the window (and for the Document Window, this will also close the document and other windows). Without a mouse, just press the ESC key to close a window. Secondly, note the scroll bars at the right hand side and bottom of the Document window. Clicking on the arrows will scroll the document in the direction indicated. You can also click in the areas above and below the position indicator, which will cause the document to scroll up or down a screenfull at a time. (Note that in this version, you can't use the mouse to move the position indicator yourself - this is a feature which will be included in later versions). Without a mouse, you can just use the arrow keys or Page Up and Page Down keys to scroll the document. If you have a mouse, you can also re-size and re-position the window on the screen. This may be useful when you have the Chapter or other windows also open. Holding down the Control (CTRL) key on your keyboard and pressing HOME will go to the start of the file. Holding down the Control (CTRL) key on your keyboard and pressing END will go to the end of the file. 5.4 Window Highlighting ───────────────────────────────────────────────────────────────────── AUTOREAD Version 2 works with several kinds of windows. The Document Window, the Chapter Window, the Keyword Window, and the Bookmark Window. All of these windows can be open (or visible) at the same time, and each allows you to use the keyboard to scroll through their contents, or take some action on the current item. So how does the program know which window you want to scroll, or to action? The answer is that keystrokes always go to the currently highlighted window. You can tell which is highlighted by the bright colour of its border. You will often need to change which window is highlighted in Autoread Manual -8- order to make use of it. You can highlight a visible window (or make a hidden window visible and highlighted) in two different ways: * By clicking on it with the mouse (if it is visible); * By pressing the "hot key" associated with the "View" choice for that window, eg pressing F2 will make the Chapter window visible and highlighted, pressing Home will make the Document Window highlighted. * By selecting "View" from the appropriate menu. Autoread Manual -9- 6. A Brief Tour of the AUTOREAD Menu Bar ════════════════════════════════════════ This chapter just gives you a quick overview of the choices available. Further details of each menu bar choice are given in subsequent chapters. 6.1 The = Menu ───────────────────────────────────────────────────────────────────── This is sometimes called the control menu. There are only two choices, the first "About" calls up copyright information about AUTOREAD. The second is "Help", which brings up a simple help screen. (For more detailed help, I suggest closing your current document and calling up the AUTOREAD on-line manual - AUTOREAD is its own best help system! 6.2 The File Menu ───────────────────────────────────────────────────────────────────── The File menu lets you open and close documents, and to exit the program. Note that you can close a document either by selecting this choice, or by clicking on the close button of the Document Window, or by pressing ESC when the Document Window is highlighted. You may be surprised that there are no "Save" options on this menu. That is because you always use AUTOREAD on existing documents, and because chapter and keyword information is automatically saved when necessary as you close the document. Note, however, that this means that if you have created a lot of new chapter stops you should close the document down properly rather than just turning off the computer. 6.3 The Document Menu ───────────────────────────────────────────────────────────────────── The choices on this menu are only active when you have opened a document. Note the first choice - View, with a "hot key" of Home. You will need to select this, or to press Home, in order to highlight the Document Window when another window such as the Chapter window is currently highlighted. The Document menu allows you to move quickly to different positions in the file: the beginning, the middle, the end, or to a specific line number, or to find a particular page number. There is also a choice on this menu called "Preferences", which lets you set certain preferences for how you want AUTOREAD to treat this particular document. 6.3 The Chapter Menu ───────────────────────────────────────────────────────────────────── This is perhaps the most powerful part of AUTOREAD. This menu allows you to find instantly any one of potentially thousands of 'chapter stops', by selecting a description from a pull-down menu. They are called 'chapter stops' because the idea is that you can set up such stops at the beginning of chapters or major sections in the document. The number of chapter stops allowed in the shareware version of Autoread Manual -10- AUTOREAD is 400; however if you register, you will be allowed to set as many chapter stops as you wish up to the limits of the memory on your computer. This menu allows you to find, create, delete or change an existing chapter stop. It also allows you to clear all existing chapter stops, or to automatically make chapter stops at standard points in a document. 6.4 The Keywords Menu ───────────────────────────────────────────────────────────────────── An AUTOREAD keyword is like a FIND command for pre-defined strings. It means you can create a list of common or especially important words, perhaps from the index of the manual, and quickly point to them. The current version allows you to have up to 250 keywords. Once you have chosen a keyword to find, AUTOREAD will quickly scan the file looking for the next occurrence of that keyword. This menu allows you to find, create, or delete keywords. 6.5 The Bookmarks Menu ───────────────────────────────────────────────────────────────────── Bookmarks work in a very similar way to chapter stops, except that they are normally temporary (they vanish when you exit AUTOREAD unless you've chosen "Save Bookmarks" as part of the document preferences), and the listing entries simply give the bookmark number and the first text on the line marked. Bookmarks are intended as a quick way of placing a marker in the text while you look for some other information, and then being able to quickly return to where you left off. Note also that if you've chosen "Save Last Session" in the document preferences, when you exit AUTOREAD the current position in the file when you exited is stored, and when you restart this position is automatically set as Bookmark 0, and marked "LAST SESSION" . If you've also chosen "Start At Last Session" in the preferences, the document will automatically go to this position when opened. 6.6 The Search Menu ───────────────────────────────────────────────────────────────────── This menu lets you search for any text (not a pre-defined keyword), either in the body of the document, or in the Chapter descriptions. This latter search is a very quick way to search for a major topic which is covered by a chapter heading. 6.7 The Utilities Menu ───────────────────────────────────────────────────────────────────── This menu has several choices which allow you to do various useful things: send part of the document to a printer or another file; Autoread Manual -11- specify the location of files that AUTOREAD needs; or change the screen mode (the number of lines on the screen). Autoread Manual -12- 7: Document Menu ═════════════════ The Document Menu looks like this: ┌────────────────┐ │ View Home│ │ ---------------│ │ Top ^Home│ │ Middle -│ │ End ^End│ │ ---------------│ │ Line Number │ │ ---------------│ │ Page Number │ │ Odd Page Set │ │ Even Page Set │ │ ---------------│ │ Preferences │ └────────────────┘ The Document menu is primarily to give you several ways of moving around in the document, and to set document preferences. 7.1 View (Home) ───────────────────────────────────────────────────────────────────── You need to select this, or to press the Home key, to highlight the Document Window, and to bring it to the front (on top of any other windows you may have open). Only when the Document Window is highlighted will the rest of the choices on this menu work. The next four choices on the menu should be self-explanatory: 7.2 Top(^Home) ───────────────────────────────────────────────────────────────────── Goes to the start of the file. 7.3 Middle ───────────────────────────────────────────────────────────────────── Goes to the very middle line of the file. 7.4 Bottom (^End) ───────────────────────────────────────────────────────────────────── Goes to the end of the file. 7.5 Line Number ───────────────────────────────────────────────────────────────────── Lets you enter and go to a particular line number in the document. 7.6 Page Number ───────────────────────────────────────────────────────────────────── This is a very valuable function, allowing you to search for particular page numbers in the document. This is very useful if the Autoread Manual -13- document comes with a contents page and index page which shows these page numbers. Searching for a page number is not as easy as it might sound, however, because simply looking for a number such as say 25 will locate many erroneous instances of the number which are not page numbers, such as in tables, prices, and so on. So AUTOREAD requires that you set a 'template' for what the page numbering looks like in the document. Fortunately, this is very easy to do, and only needs to be done once. This process is described in the following two sub-sections. Once you have created the template for a particular document, you will never need to do it again, as AUTOREAD writes the template(s) to the .ARD file. This may all sound complex. However, FINDING a page once the template is set could not be easier. Simply choose Page Number from the Document Menu, and then enter the desired page. Note that you can enter such constructs as '2-25' with no problems. AUTOREAD then does a text search for the desired page, checking instances of the number against its template. You will note that the dialog box asks you if you want to start searching globally, that is, from the top of the document, or from your current position. The latter will be quicker if you are confident the wanted page is further down in the document. NOTE: Page find is far from perfect. Its success will depend on the consistency of the way the manual author has set up page numbering. 7.7 Odd Page Set ───────────────────────────────────────────────────────────────────── To set up the page numbering template for odd pages, position the document so that a line containing an odd page number is the current line (with the < arrow symbol at the very right hand of the screen - if you have not set any screen offset in the document preferences, this will be the top line of the screen). E.g., in the Telix manual, I positioned a line like this as the current line: Telix v3.12 5 When you choose Odd Page Set, you will be shown the current line (shorn of any unnecessary spaces at beginning and end, and perhaps broken over two lines to fit into the dialog box) and asked what the embedded page number is - in the example given it was 5. With numbering of the form 2-5, you should enter this whole construct, i.e. 2-5, not just 5. That's all there is to it. You will see that in the dialog box there is also a check box marked "At Bottom of Page", and an input line to enter the page size. You will only need to use these if the document author has placed the page numbering at the bottom of the page, rather than the top. If you Autoread Manual -14- check the box, AUTOREAD will automatically offset the display by the page size you have given, so as to bring the top of the wanted page to the top of the display. You may need to experiment with this a little to get it right. NOTE: If you don't explicitly do an Even Page Set, AUTOREAD assumes that even numbered pages are identical to odd numbered pages unless told otherwise. The same applies if you just do an Even Page Set and not an Odd Page Set. You only need to set both if the headers for even and odd pages are different. NOTE: Avoid positioning on a page whose number is embedded in other text on the line, e.g., in the example given above it would have caused problems to position on page 3,1,2 or 12, as these numbers are all embedded in the 'Telix v3.12' string. 7.8 Even Page Set ───────────────────────────────────────────────────────────────────── This is identical to Odd Page Set, except you should position the current line to an EVEN numbered page. You only need to do this if the format for even pages is different from that for odd pages. 7.9 Preferences ───────────────────────────────────────────────────────────────────── This is a very important choice, allowing you to set may different choices which affect how AUTOREAD will behave with the current document. The preferences are saved in the .ARD file. The current preferences you can set are as follows: 7.9.1 Chapter Sort Order ───────────────────────────────────────────────────────────────────── Normally, AUTOREAD displays chapters in "natural" order, that is, the order in which they appear in the document (line order). However, you can change this so that the chapters are listed in alphabetical order of their descriptions. This can be very useful for some kinds of application. NOTE that changing the sort order does not affect the current chapter window. To make the changed order take effect, you must close the document and re-open it. (This is a change from versions prior to 2.00, but it has the advantage that AUTOREAD will always use the nominated order for this document). Note also that you will normally want to set Show Level Prefixes off (next preference) if you want alphabetical order. 7.9.2 Show Level Prefixes and Level Prefix Symbol ───────────────────────────────────────────────────────────────────── From version 2.00, you can nominate a "level" for chapter stops (see next section for more detail). This allows subsidiary headings to be treated differently from major headings, by indenting with a nominated symbol. Autoread Manual -15- Normally, Show Level Prefixes is on, but you can uncheck this box to turn off this effect. You can also nominate the symbol(s) you want to use to mark levels. 7.9.3 Offset Display ───────────────────────────────────────────────────────────────────── In some applications, it is useful to have AUTOREAD display a few lines before the line on which a chapter stop has been set (an example would be in long listings of bulletin board messages, where the "Subject" line is generally three or four lines below the top of the message). By setting the offset to a value other than zero, you can have AUTOREAD behave in this way. It is not, however, a good idea to set this value to anything more than, say, half a screen, or AUTOREAD may behave in unexpected ways. 7.9.4 Save Last Session ───────────────────────────────────────────────────────────────────── If you check this box, AUTOREAD will automatically save the position in the document where you were at when you closed the document. From version 2.00, this information is saved in the .ARB file, as Bookmark 0, described as Last Session. 7.9.5 Start at Last Session ───────────────────────────────────────────────────────────────────── If you check this box, AUTOREAD will automatically open the Document Window at the Last Session (Bookmark 0) point. This allows you to keep reading through a long document through several sessions. NOTE that if you check this box but the Last Session has not previously been saved, you will start at the top of the document, as usual. 7.9.6 Save Bookmarks ───────────────────────────────────────────────────────────────────── I always intended Bookmarks to be simply a temporary version of Chapter stops, but after numerous requests from users, Bookmarks are now saved in the .ARB file if you choose this option. Autoread Manual -16- 8: Chapters Menu ═════════════════ The Chapters Menu looks like this: ┌─────────────────┐ │ View F2 │ │ Find Enter │ │ Add Ins │ │ Delete Del │ │ Edit Ctrl-F2 │ │ Promote Grey + │ │ Demote Grey - │ │ -------------- │ │ Clear │ │ Make │ └─────────────────┘ As indicated earlier, 'Chapter Stops' are perhaps the most powerful part of AUTOREAD. You can use it to move instantly to the beginning of various chapters or sections within the text file. This menu allows you to find instantly any one of hundreds of 'chapter stops', by selecting a description from a pull-down menu. The Chapters Menu also allows you to add, change and delete such chapter stops, as described below: 8.1 View (F2) ───────────────────────────────────────────────────────────────────── You will need to take this choice, or press the "hot key" to make the Chapter Window visible and highlighted, and to make the following choices work. Note that the Chapter Window can be resized and repositioned anywhere you like, and that it stays visible until you close it, or until you select the Document Window (which comes to the front and may obscure the Chapter Window. You can page up and down through the Chapter Window the same way as you can with the Document Window. Note also that the Chapter Window stays scrolled to the same spot where you left it last. 8.2 Find(Enter) ───────────────────────────────────────────────────────────────────── Once you have selected your desired chapter stop, press ENTER, or double-click on it with the mouse, and the Document Window will immediately scroll to the text starting at the desired chapter stop. The Document Window will be selected so you can see the text of the document. If you want to choose another chapter, press F2 again: the Chapter Window will still be scrolled to the place you were at before. 8.3 Add Current Line (Ins or Alt-A) ───────────────────────────────────────────────────────────────────── This allows you to set the current line (that is, the line currently at the top of the display screen) as a chapter stop. If you make this choice from the Chapters menu, you will be prompted for a description. Autoread Manual -17- However if you use the Alt-A key when the Document Window is highlighted, there are no prompts - the computer will make a warbling sound to show that it has captured the current line. Note that as part of the dialog box, you can set a "level" for the current chapter stop. Higher level numbers indicate more and more subsidiary chapters, which are indented to the right in the Chapter Window, allowing you to naturally reflect the structure of the document with its major headings and sub-headings. Future versions of AUTOREAD may allow you to supress display of lower level headings. 8.4 Delete ───────────────────────────────────────────────────────────────────── This will allow you to get rid of a particular chapter stop. You'll probably use this a good deal after carrying out a Chapter Make function. 8.5 Edit ───────────────────────────────────────────────────────────────────── This will allow you to edit the description of a particular chapter stop. 8.6 Promote & Demote ───────────────────────────────────────────────────────────────────── These options allow you to easily change the level of a chapter stop. Promote (the + key on the numeric keypad) reduces the level number by one (lower levels meaning higher priority). Demote (the - key on the numeric keypad) increases the level number and indents the chapter description accordingly. 8.7 Clear ───────────────────────────────────────────────────────────────────── This allows you to get rid of ALL current chapter stops. Please use this carefully! You will be prompted to confirm the clear. 8.8 Make ───────────────────────────────────────────────────────────────────── This is an extremely powerful utility, which allows you to automatically create chapter stops from various kinds of clue in the text of the document. If you choose Make, you are taken to a sub-menu, which looks like this: ┌────────────┐ │ Textual │ │ Procedural │ │ UpperCase │ └────────────┘ These options are each described in the following sections. Note: you can run any form of Make repeatedly on a file to identify different levels of sections. However, in this version of AUTOREAD, the software will not let you add two identical chapter stops - the second will just never be added. "Identical" depends on whether you have the chapter sort order set to Line or Alpha. If it is Line, you can't set two chapter stops which jump to the same line. If it is Alpha, you can't set two chapter stops with identical descriptions. For this reason, there is no need in this version for the "Remove" option in earlier versions which eliminated such duplicates. Autoread Manual -18- 8.9 Textual Make ───────────────────────────────────────────────────────────────────── Textual make is the most secure form of the Make command, but will only work for documents where the document author has used a standard way of identifying chapter or section beginnings. Textual Make allows you to scan the whole document, looking for a designated string of text, and setting a chapter stop once it has found it. It is possible to set a line offset from the searched for text, and to specify which "level" the chapter stop should be at. An example will make this easy to understand. 8.9.1 A Textual Make Example ───────────────────────────────────────────────────────────────────── One of the first documents I used AUTOREAD on myself was the manual for the excellent shareware text editor QEDIT. This manual is some 5500 lines long. The document author had used a line of equal signs '====' to underline each chapter heading, and a graphic line '_____' to underline each section heading. I first made a pass with Textual Make, searching for the line of equal signs. Once I selected Textual Make, I was prompted for the text string to search for. I entered four equal signs, =====. I entered a line offset of 1, and specified that the chapter description was ABOVE the found text, that is, immediately above the underlining found. If I had wanted the line of equal signs itself to be the chapter stop, I would have entered a line offset of 0. I also specified that these chapter stops should have the highest level of significance, and so set Level to 1. The program then took about 30 seconds to scan through the whole QEDIT document and set up the chapter stops. AUTOREAD took the first text on the line I indicated I wanted the chapter stop on, and used this as its description for that chapter stop. I then wanted to set up sections as chapter stops, so I carried out another pass with Textual Make. Once I selected Textual Make, I was prompted for the text string to search for. I entered four graphic line characters, '____'. (I used the ALT key and the numeric keyboard to enter these characters - refer to your DOS manual if you don't know how to do this). Again the wanted line was the one above the graphic line, I entered an offset of 1, and clicked on ABOVE. This time I set the Level to 2, to make these chapters subsidiary headings. Autoread Manual -19- Another 30-40 seconds, and I had essentially the equivalent of the contents page of the manual in the form of a pull-down menu. Here is part of the chapter stops menu I created for QEDIT.DOC: ┌──────────────────────────────────────────┐ │ - COLORS │ │ - TABLE OF CONTENTS │ │ - ACKNOWLEDGEMENTS │ │ - INTRODUCTION │ │ - FEATURES │ │ - SYSTEM REQUIREMENTS │ │ - INSTALLATION │ │ CHAPTER 1. USERS GUIDE FOR QEDIT │ │ - QUICK START │ │ - MENUS │ │ - THE STATUS LINE │ │ - FILES │ │ - VIEWING AND GETTING AROUND IN THE TEX │ │ - CURSOR MOVEMENT │ │ - USING WINDOWS │ └──────────────────────────────────────────┘ If you are using AUTOREAD on a document you are editing, then I recommend the use of the stand-alone Make utility, described below. Note that the means of designating chapter stops need not be types of underline, as in the example above, but could be the word CHAPTER in capitals (Note that Make distinguishes between upper and lower case, unlike Find Text and Find Keyword), or a special character or series of characters (e.g. ---> ). The best way to learn how Make works is to try it out. Don't worry about making mistakes, you can always Clear and start again. 8.10 Procedural Make ───────────────────────────────────────────────────────────────────── I added this function after I had been using AUTOREAD myself on quite a number of different shareware manuals. While the textual make function works very well for manuals where the author has used some standard form of underlining or text identifying the start of chapters and sections, it proves awkward for instances where the author has only used section numbering of the 'procedural' form, i.e.: │ 1. INTRODUCTION │ 1.1 Hello │ 1.2 Goodbye │ 1.2.1 Farewell │ 1.2.2 Cheerio. So I added this function. The dialog box for Procedural Make will let you specify whether the section numbering is numeric or alphabetic (some authors have appendixes sectioned off in the form:A.1, A.2, B.1, etc). You can also specify what the separation character should be (in most cases this will be a period, which is the default). Once you have made these choices, the program takes over. If numeric sectioning was chosen, then AUTOREAD will identify as a chapter stop Autoread Manual -20- any line whose first text was a number, and if that number was followed by a period (or other separator you specified) before any other character. It will also count the number of periods in the section number, and set the Level for the description appropriately. If alphabetic sectioning was chosen, then AUTOREAD will identify as a chapter stop any line whose first character was an upper-case letter and whose second character was a period (or specified separator). 8.11 UpperCase Make ───────────────────────────────────────────────────────────────────── I added this form of Make when I discovered that there were manuals (PKZIP is a good example) where the ONLY indication of a chapter or section heading was that the heading was all in upper case (capitals). UpperCase Make works by checking each line of the document to see if it is all in upper-case. Because this is such an uncertain means of identifying chapters, the dialog box allows you to set several other conditions relating to whether non-alpha characters are allowed at the beginning or ending of the line, and whether blanks preceding the text are allowed or required (some authors centre their uppercase headings). Note that if you specify than N blanks MUST be present, this overrides a specification that LESS than N blanks are allowed. Any line meeting all these requirements will be identified as a chapter stop. 8.13 Problems with Make ───────────────────────────────────────────────────────────────────── Almost inevitably, with any of the above forms of Make, you will end up with some invalid chapter stops. You can either use the Delete function from the Chapter menu to remove these, or edit the .ARD directly (see APPENDIX C on page 36). One particular trap with Procedural Make is Contents Pages. AUTOREAD naturally cannot tell the difference from a section heading in the body of the text and that heading repeated in the Contents Page. If you have a document with a problem contents page, simply position the current line so it is after the contents page, and then when you do the make, select "From Current Line" rather than "From Beginning of Document" in the dialog box. UpperCase Make is very subject to erroneous entries, because all it has to go on is a line which is all in capitals. However, the additional conditions you can now set in this version allow you to eliminate some false hits, and it is now also much easier to delete erroneous entries as you step through the document. 8.13 The Stand-Alone Make Utility ───────────────────────────────────────────────────────────────────── Particularly for the use of those using AUTOREAD as a help system, and for shareware authors who might like to distribute a special version of AUTOREAD with their shareware manuals (see page 30), I have provided a stand-alone chapter make utility, CHAPMAKE.EXE. This is also useful to anyone using AUTOREAD on a document which for whatever reason has to be altered regularly. Autoread Manual -21- The advantage of this utility is that it allows you to set up an automated chapter make which you can run each time you have made a significant change to your manual or other document you wish to use AUTOREAD on. To run CHAPMAKE, enter a command line such as the following: CHAPMAKE MANUAL However, you must first create a text file with the make commands in it. This file normally has the same name as the document you'll use AUTOREAD on, but with an extent of .MAK. So if your document is called MANUAL.DOC, then the make file will be called MANUAL.MAK. Note however that you can optionally use a standard make file by including its name on the command line, e.g.: CHAPMAKE MANUAL STANDARD.MAK This has the advantage of being able to use a single standard make file for several different manuals. The make file can have any number of command lines. The current commands are described as follows: 8.13.1 C - Clear Chapters ───────────────────────────────────────────────────────────────────── A line with the character 'C' at its start will clear all existing chapter stops, just as if you had selected Clear from the Chapters Menu. Note that any existing keywords are left untouched. 8.13.2 T - Textual Make ───────────────────────────────────────────────────────────────────── A line starting with 'T' has the effect of a Textual Make command as selected from the Chapters Menu. The 'M' must be followed by the text to search for, the line offset, and the level, all separated by slashes (/). These are exactly as you would enter them in the menu-driven make utility within AUTOREAD. For example, take the following line: T/***/-1/1 This line in the make file would set up as chapter stops the lines preceding the text ''***", and would set the level to 1. 8.13.3 N - Numeric Procedural Make ───────────────────────────────────────────────────────────────────── A line beginning with 'N' acts exactly as if you had chosen Procedural Make from the Chapters Menu, and then selected Numeric section numbering. You can follow the 'N' with a slash and a character to indicate the separator if it is anything other than a period. Autoread Manual -22- 8.13.4 A - Alphabetical Procedural Make ───────────────────────────────────────────────────────────────────── A line beginning with 'A' acts exactly as if you had chosen Procedural Make from the Chapters Menu, and then selected Alphabetic section numbering.You can follow the 'A' with a slash and a character to indicate the separator if it is anything other than a period. 8.13.5 U - UpperCase Make ───────────────────────────────────────────────────────────────────── A line beginning with 'U' acts exactly as if you had chosen UpperCase Make from the Chapters Menu. 8.13.6 Example Make File: ───────────────────────────────────────────────────────────────────── This is the Make file I use for the AUTOREAD manual: C T/ ═════/-1/1 N 8.13.8 An Important Note! ───────────────────────────────────────────────────────────────────── At present, CHAPMAKE is limited in how much you can control the make process. This means that you can't specify a starting line for any methods (CHAPMAKE will start searching at the beginning of the document), nor can you specify conditions for the uppercase make type. Autoread Manual -23- 9: Keywords Menu ═════════════════ A keyword is simply a text string to be found in your document, and the Find Keyword function works exactly as does the Find Text function, except that you don't need to type in the required text: you simply select it from a pull-down menu. The Index of a document is a great place to find useful keywords. The Keywords Menu looks like this: ┌──────────────────┐ │ View F3 │ │ Find Enter │ │ Add Ins │ │ Delete Del │ │ Edit Ctrl-F3 │ └──────────────────┘ 9.1 View (F3) ───────────────────────────────────────────────────────────────────── This brings up a scrolling window of the existing keywords. You can move the highlight to the wanted keyword by using the up and down arrow keys or the scroll bars. 9.2 Find (Enter) ───────────────────────────────────────────────────────────────────── Once you have selected your desired keyword, press ENTER, and the screen will begin searching from the current line for the wanted keyword. If the keyword cannot be found, an error message will appear. Note that unlike the Chapter Make command, Find Keyword IGNORES the difference between upper and lower case. That is, 'DOS', 'Dos' and 'dos' will all be found by the same keyword choice. Once the keyword is found, the first occurrence of the wanted keyword will be on the top line of the Document Window, and all occurrences of the keyword on the current screen will be highlighted in the current highlight colour. 9.3 Add (Ins) ───────────────────────────────────────────────────────────────────── This prompts you for the text of a new keyword, which will be added to the list of existing keywords in alphabetical order. 9.4 Delete (Del) ───────────────────────────────────────────────────────────────────── This will allow you to get rid of a particular keyword. 9.5 Edit (Ctrl-F3) ───────────────────────────────────────────────────────────────────── This lets you change the highlighted keyword. Autoread Manual -24- 10: Bookmarks Menu ═══════════════════ Bookmarks are just like chapter stops - except that they are volatile (they vanish when you exit AUTOREAD), and that they do not have a description, just an ID number and a line number. Bookmarks are intended as quick reference points to 'hold your place' when you are looking for something else in a file. You can only create a maximum of 10 bookmarks. The Marks Menu looks like this: ┌─────────────────┐ │ View F4 │ │ Find Enter │ │ Add Ins │ │ Delete Del │ │ Edit Ctrl-F4 │ └─────────────────┘ 10.1 View (F4) ───────────────────────────────────────────────────────────────────── This brings up a scrolling window of the existing bookmarks. You can move the highlight to the wanted bookmark by using the up and down arrow keys or the scroll bars. 10.2 Find (Enter) ───────────────────────────────────────────────────────────────────── Once you have selected your desired bookmark, press ENTER, and the Document Window will immediately fill with the text starting at the desired bookmark. 10.3 Add (Ins) ───────────────────────────────────────────────────────────────────── This allows you to set the current line as a bookmark. Note that, as with Chapter stops, you can alter the text of the description as you wish (eg, you could change it to read "IMPORTANT BIT ON BOOKMARKS"). You will be prompted for the bookmark number you wish this line to be recorded against. You can have up to 9 bookmarks at any one time. 10.4 Delete (Del) ───────────────────────────────────────────────────────────────────── This clears the currently highlighted bookmark. 10.5 Edit (Ctrl-F4) ───────────────────────────────────────────────────────────────────── This lets you alter the currently highlighted bookmark. Autoread Manual -25- 10.6 Function Key Setting & Finding Marks ───────────────────────────────────────────────────────────────────── Because bookmarks are mainly used for very rapid access to temporary locations in the file, AUTOREAD allows you to completely bypass the menu system in setting and finding bookmarks. While you are in the Document Window and at a point in the text you wish to return to after looking somewhere else, hold down the SHIFT key and one of the function keys F1..F9. You will hear a warbling sound, indicating that the equivalent bookmark has been set at that point (i.e., pressing Shift F2 sets bookmark 2). After you have browsed elsewhere, you can hold down the ALT key and the function key (F1...F9) corresponding to the bookmark you set previously. You will immediately jump back to the place you left. Note that you can use ALT and the function keys to jump to ANY bookmark, whether set with SHIFT + function key or set through the Bookmarks menu. NOTE: If you have selected Save Last Session in the document preferences, AUTOREAD will automatically make bookmark 0 correspond to the last position you were reading when you closed the document last time. ALT-F10 will take you to this bookmark immediately, or you can just select it from the Bookmarks Window. Autoread Manual -26- 11: Find Menu ══════════════ The Find Menu looks like this: ┌────────────────────────────┐ │ Find Text F5 │ │ Last Find: F6 │ │ -------------------------- │ │ Find In Chapter: Ctrl-F5 │ │ Last Chapter Find: Ctrl-F6 │ └────────────────────────────┘ 11.1 Find Text (F5) ───────────────────────────────────────────────────────────────────── This will prompt you for the text to be found. You can specify whether you wish the match to ignore upper and lower case distinctions, and the direction of the search. Once you have entered your desired text, press ENTER or click on the OK button, and the screen will begin searching in the indicated direction for the wanted text. If the text cannot be found, an error message will appear. Once the wanted text is found, the first occurrence of the wanted text will be shown on the top line of the Document Window, and all occurrences of the wanted text on the current screen will be highlighted in the current highlight colour. 11.2 Last Find (F6) ───────────────────────────────────────────────────────────────────── This retains a memory of the last text string you looked for, and enables you to select it again. Otherwise, it works exactly like the Find Text command. Note that finding a keyword is treated as a find-text command, so that Last Find can be used to repeatedly find the same keyword. 11.3 Find In Chapter (Ctrl-F5) ───────────────────────────────────────────────────────────────────── This allows you to search for a text string in the Chapter Stop list. This can be a very quick way to find a topic in a large document, which has hundreds of chapter stops. Find In Chapter searches ONLY the chapter stop descriptions. Otherwise, it works exactly like find text. 11.4 Last Chapter Find (Ctrl-F6) ───────────────────────────────────────────────────────────────────── This just searches again in the chapter descriptions from the current point for the same text as your last chapter search. Autoread Manual -27- 12.: Utilities Menu ════════════════════ The Utilities Menu looks like this: ┌─────────────┐ │ Screen Mode │ │ Directories │ │ Output Text │ └─────────────┘ 12.1 Screen Mode ───────────────────────────────────────────────────────────────────── This brings up a dialog box which lets you alter the number of lines you can see on your screen (provided your video card and monitor support this). Using AUTOREAD with more than 25 lines on the screen is often the best (if you have good eyesight), because you can see quite a bit of the document text while keeping the Chapter Window visible and handy. 12.2 Directories ───────────────────────────────────────────────────────────────────── The ONLY time you will need to use this option is if you have a particular wish or need to place the AUTOREAD-created files in a directory other than the one that the document you are reading is in. Why might you need to do this? Well, the source document might be on a write-protected disk, for example, and using the AUTOREAD defaults would cause trouble, because the program wouldn't be able to create an index file on that disk. A classic example would be a document on a CD-ROM, which is by definition write-protected. Or you might be on a network, where the source document and its index are on a server, but you want to keep your own personal bookmarks file in your personal directory. Altering the default directories gives you a lot more flexibility. Note, however, that you must alter the directories BEFORE you open the source document. You can also do this on the command line (see page 35), allowing you to open a document on the command line with the directories set as you wish them. 12.3 Output Text ───────────────────────────────────────────────────────────────────── This choice allows you to copy ('dump') parts of the document you are reading either to another file, or to the printer. The choices shown in the dialog box for this choice relate to what parts of the document you wish to be dumped, and whether you wish to dump to a file or a printer. In the case of a file, you must enter a file name. If the file already exists, you will be asked if you wish to append to the end of the file, or to overwrite the existing file (i.e., destroy it and start again). The following describe the action of the various dump dialog box options for the scope of the material to be dumped. Autoread Manual -28- 12.3.1 Screen ───────────────────────────────────────────────────────────────────── Choosing this will dump just what you can see on the display screen at the current time, less the top and bottom status lines. 12.3.2 Chapter ───────────────────────────────────────────────────────────────────── This will dump the entire current chapter or section. AUTOREAD will determine the 'current chapter' as the material between the chapter stop prior to the current line number, up to the line before the chapter stop following the current line number. If you position a chapter stop heading as the current line, then dump, you will dump from that heading to just before the next chapter stop heading. 12.3.3 Lines ───────────────────────────────────────────────────────────────────── This lets you enter your own start and ending line for the dump. Entering '1' for the first line, and some number larger than the last line in the file will dump the entire document. 12.3.4 Page Break ───────────────────────────────────────────────────────────────────── This simply lets you send a form feed to the printer, or to embed a form-feed character (^L) in the file. Autoread Manual -29- 13: The Read-Only Version ══════════════════════════ For companies wishing to use AUTOREAD to set up on-line help systems, shareware authors, and others wanting to distribute a version of AUTOREAD with manuals, there is a special "read-only" version of AUTOREAD (called READAUTO) which omits some features (such as Make), which are of use only to users wanting to use AUTOREAD on any document, and prevents users from making changes to your chapter stops and keywords. Please contact me about a license fee which will allow you to distribute as many copies of the special version with your own manuals as you require. You will find it very easy to set up the customised version of AUTOREAD to work with your manual, establishing chapter stops and appropriate keywords, so that your users will find your on-disk manual a truly easy-to-use and valuable reference. Autoread Manual -30- 14: Acknowledgements ═════════════════════ AUTOREAD was written using Borland's Turbo Pascal (Versions 5.5 and 6.0), a great compiler which goes on getting better and better, especially with the Turbo Vision interface I have used in version 2.0. I used QEDIT Advanced 2.08 from SEMWARE as my text editor during programming and for early versions of this manual. I've also mentioned QEDIT in a number of places in this manual, to illustrate how AUTOREAD can be used to make access to a large text file manual easy, and I hope SEMWARE didn't mind me doing so! QEDIT is still terrific, but SEMWARE have just developed an even better editor called The Semware Editor (TSE), which is phenomenal! For these products, I recommend you write to SEMWARE at Suite C3A, 4343 Shallowford Rd, Marietta, GA 30062-5022 USA for their current prices. The printed version of this manual was produced with Microsoft Word for Windows, on a Hewlett-Packard DeskJet 500, both terrific products. Thanks to Don Avila, Russell Herman, Jerrold Maxwell, Terry Allen, Rick Foster, Ralph Bednarski and many others for reporting bugs and suggesting improvements to AUTOREAD. Autoread Manual -31- 15: Version History ════════════════════ This is version 2.00 of AUTOREAD, and it is a total re-write from versions 1.00 thru 1.10. There may still be a few bugs in it. I would be grateful if those who find such bugs could let me know. Similarly, if you have any ideas for ways of improving the product, please let me know. In particular, there are some features of AUTOREAD version 1.10 that I have had to leave out of version 2.00 because of the different way things are handled under the Turbo Vision interface (and to prevent the program size blowing out even more!). I really need to know how important these missing features are to you. If they are vital, I will make every effort to re-instate them. 15.1 Updates ───────────────────────────────────────────────────────────────────── │ 1.01 : (2 July 1990) │ - GLOBAL search direction added │ - fix to bug allowing line 0 to be displayed in status │ - fix to bug involving embedded '/' char in chapter description │ │ 1.02 : (5 July 1990) │ - added highlighting of keywords and found text │ - changed index file extent from .IDX to .ARI │ │ 1.03 : (6 July 1990) │ - added procedural make. │ - support for 43-line and 50-line screens. │ - added alpha sort for chapters │ - added stand-alone make utility │ │ 1.04 : (14 July 1990) │ - added F1 function key for Help │ - added F5 function key for Last Find │ - added F6 function key for Jump to Next Chapter Stop │ - fixed Upper/Lower case problem with highlighting │ - fixed bug with files of longer than 32k lines │ - added Crawl Read │ │ 1.05 : (23 July 1990) │ - added UpperCase make and set up Make sub-menu │ - increased maximum chapter stops to 500 │ │ 1.06 : (1 August 1990) │ - added F7 function for instant Add Chapter │ - added Page Find function │ │ 1.07 : (6 August 1990) │ - added Dump function │ - added F5 for Find Text, rearranged other function keys │ │ 1.08 : (20 September 1990) │ - fixed bug preventing last line of file being seen │ - added saving of screen colours to .ARD file │ - added screen offset feature │ - improved indexing procedure │ Autoread Manual -32- │ - added Alt-Q - Quit Without Data Save │ - added Remove Duplicates to Chapter Menu │ │ 1.09 : (28 March 1991) │ - changed file indexing procedure, to fix errors some users getting │ with old method. │ │ 1.10 : (19 October 1991) │ - added file buffering │ - added In Chapter Find (find text in chapter heading) │ - added -F find text command-line option │ - altered format of .ARD file │ - added New Page option to Dump menu │ - altered Bookmark display (now includes first text on marked lines) │ - altered Last Session handling (now places bookmark instead of │ immediate jump) │ │ 2.00 : (11 December 1992) │ - Complete rewrite │ - Much better user interface: mouse control, scroll bars, standard │ menu behaviour. Menu options always visible. │ - Chapter, Keywords and Bookmarks windows moveable and resizable. │ Also now retain their current scrolled position. │ - Dialog boxes now offer greater choice without having to ask a series │ of tedious questions. │ - Much larger documents can be accessed - anticipated (but not tested) │ to be able to handle files of in excess of 2 million lines. (Note │ that only the registered version has this capability) │ - No limits (in registered version) to number of chapter stops or │ keywords, within available memory. │ - Chapter descriptions no longer limited to 40 characters wide. │ - Easy alteration to 43/50 screen line display through Utilities. │ - Bookmarks can now optionally be saved. │ - Behaviour of Autoread for a particular document can be altered │ through Preferences. │ - Now keeps track of whether .ARD file needs to be re-saved. │ - Index (.ARI), Data (.ARD) and Bookmarks (.ARB) files can optionally │ reside in a different directory to the document file. This allows │ AUTOREAD to be used on documents residing on read-only or write- │ protected disks (for example, with text documents residing on CD-ROM). │ - AUTOREAD can be left running while documents are closed and opened. │ - Document selection through standard dialog box. │ │ 2.01 : (10 May 1993) │ - A number of bugs in 2.00 fixed. │ - Promote and Demote levels added │ - Changed behaviour of Chapter, Keyword and Bookmarks windows after a │ find entry (document window now automatically selected). │ │ DRAWBACKS/OMISSIONS in Version 2.0x: │ │ - Screen colours no longer selectable (this will be provided in future │ versions). │ - "Crawl Read" not currently supported. │ - Executable file is now much bigger ~160k rather than ~60k. Autoread Manual -33- APPENDIX A: FUNCTION KEY SUMMARY ════════════════════════════════ F1: Help F2: View Chapter List F3: View Keyword List F4: View Bookmark List F5: Text Find F6: Repeat Last Keyword or Text Find F8: Jump to Next Chapter Heading Ctrl-F5: Find Text in Chapter Heading Ctrl-F6: Repeat Chapter Find Alt-A: Add current line as Chapter Alt-X: Quit Autoread ESC: Close Current Window Shift-F1 Thru : Set Corresponding Bookmark Shift-F9 Alt-F1 Thru : Jump to Corresponding Bookmark Alt-F9 Autoread Manual -34- APPENDIX B: COMMAND-LINE OPTIONS ════════════════════════════════ To use a command-line option, append the desired option (which must begin with a hyphen) to the command line you use to start up AUTOREAD, eg: AUTOREAD MANUAL.DOC -X -Y Note that you cannot use command-line options UNLESS you are starting up a document on the command line. That is, a line like: AUTOREAD -X -Y ...will simply ignore the command line options. The current command-line options are described below. -F"Search Text": This allows you to start AUTOREAD and immediately carry out a search for some topic. Note that the text should be in quotes if it includes a space. Note also that this option starts by searching the Chapter list for the topic, and if found, it will go straight to that chapter stop. If the topic text cannot be found in the chapter descriptions, AUTOREAD will start to search the whole text of the document. This facility is very useful for setting up "Help" systems. -Idirectory -Ddirectory -Bdirectory These options let you specify the directories where AUTOREAD will look for the document Index (.ARI), Data (.ARD) and Bookmark (.ARB) files respectively. The default in each case is the same directory as the source document. Autoread Manual -35- APPENDIX C: THE .ARD FILE FORMAT ════════════════════════════════ It's often worthwhile using a text editor directly on the .ARD file in order to tidy things up, quickly remove invalid chapter stops which were created by Make, and so on. You can also capture the index pages of the original document and massage them into a list of keywords, which you can directly append to the .ARD file. The .ARD file is just an ordinary text file. The following applies to Version 2.00 of the software. There have been some changes since version 1.10, but AUTOREAD will still read version 1.10 .ARD files. It will not, however, read .ARD files from earlier versions. However, it is a simple matter to convert these earlier .ARD files to the new format. The file is marked off into sections, each with a header of the form: #[section name]. These headers are then followed by lines of data. Here is a sample .ARD file: #[SCREEN] 0/0/0/0 #[PAGE NUMBERS] Gryll Grange Page -/50 Page -/0 0 #[PREFERENCES] L/0/N/N/Y/Y/-/ #[MISCDONE] #[CHAPTERS] Prologue/211/1 Chapter One/425/1 Intermezzo/534/2 Chapter Two/678/1 Epilogue/1009/1 #[KEYWORDS] bravery lust passion romance woe Let's look at each section in turn. The #[SCREEN] section is currently unused, but in future versions of AUTOREAD will be used to store screen colours and possibly some other information. The #[PAGE NUMBERS] section is of the following form: Autoread Manual -36- MyManual p./69 MyManual/12 0 where the text before the slash is the text that AUTOREAD uses to check that it has found a page numbering line, and the number after the slash is the column number near where AUTOREAD will check for the wanted page number in the page numbering line. If no page templates have been set, then these numbers will be -1 for both odd and even pages. The third line in this section indicates the page size, if the page numbering has been indicated to be at the bottom of the page. The next section, #[PREFERENCES] of course stores the preferences you have selected for the document, in the following order: Item 1: L or A: Indicates Line or Alpha sort order Item 2: Screen offset - an integer Item 3: Save Last Session - Y or N Item 4: Start At Last Session - Y or N Item 5: Save Bookmarks - Y or N Item 6: Show Level Prefixes - Y or N Item 7: Level Prefix characters - ASCII text. #[MISCDONE] simply speeds up processing by telling AUTOREAD that this is the end of its miscellaneous information before it hits the Chapters and Keywords. You can cut it out without any problems, but it may slightly slow down document loading. #[CHAPTERS] is of course the header for the list of chapter stops, all of which are in the following format: │ 1.0 INTRODUCTION/25/1 The text is of course the chapter description text, and the first number following the slash is the line number where the chapter begins. The second number is the level of the chapter. The #[KEYWORDS] section is of course the list of keywords, in alphabetical order. If you want to manipulate the .ARD file, feel free to do so. It is easy to simply delete or add keywords, or to delete erroneous chapter stops. Note however that you will need to know the line number if you wish to add chapter stops. The sections in the .ARD file should be in the order shown; in particular, the KEYWORDS section must follow the CHAPTERS section. Autoread Manual -37- APPENDIX D: LIMITATIONS OF AUTOREAD ═══════════════════════════════════ AUTOREAD, like most things, is not perfect. It has limitations. However, version 2.00 lifts a lot of the previous limitations on size - provided you register your copy! Version 2.00 (registered) allows the handling of files up to 2,100,000 lines in length. A typical text file with this many lines would be around 80MB in size!! The unregistered version lets you handle files of only up to 30,000 lines. There are no limitations on the number of chapter stops or keywords in the registered version, other than those due to memory limitations. On a 640K machine, you should be able to set thousands of chapter stops with no problems. Again, however, the unregistered version sets limits - 400 chapter stops and 100 keywords. What a good reason to register! AUTOREAD also has no way of determining if a file you are trying to use it on is in fact a text file. It will do very weird things if you use it on a binary file such as an .EXE file, for example. If you need to examine binary files, use the Norton Utilities or LIST. AUTOREAD will also get very confused if you feed it files with very long lines. AUTOREAD can at least handle without confusion files which include lines of up to 255 characters. Any more than that, and AUTOREAD loses track of the beginnings of lines. Autoread Manual -38- APPENDIX E: MUSINGS ON THE WRITING OF MANUALS ═════════════════════════════════════════════ I guess I was naive when I first set out to create AUTOREAD. I figured that most text file manuals would follow a similar sort of format. Alas! It is now clear that there are as many styles of manual as there are authors. This makes creating a utility like this one which will be able to do such stuff as automatically creating chapter stops very difficult. It amazes me that some authors create manuals where the section headings are barely given ANY kind of distinction from the rest of the body text. No underlinings, no section numberings, not even all in caps. Surely this makes these manuals difficult to read even in a hard copy printout? The same goes (in spades) for different ways of indicating page numbers. I guess this is a (selfish) plea for well designed manuals that AUTOREAD will work well with! Autoread Manual -39- APPENDIX F: RAVE REVIEWS AND UNSOLICITED TESTIMONIALS! ══════════════════════════════════════════════════════ "splendidly designed and immensely powerful... this little gem... we'll bet you'll soon be in love with this splendid piece of shareware." ----- "Boardwatch Magazine", November 1991: "Again thank you. Your product is a life saver for me..." ----- Shaw and Associates: "excellent product/idea!" ----- Lowell D.King "You've invented a great concept!" ----- Dan Pichulo "...very impressed...your idea of chapter location is an innovative feature..." ----- Scott Robertson